package com.urbane.openapi.config;

import org.springdoc.core.models.GroupedOpenApi;
import org.springdoc.core.properties.SwaggerUiConfigParameters;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * 全局 OpenAPI 配置类
 * 功能：
 *   - 注册公共 DTO 类型（来自 commons-dto），使其在所有服务文档中可见
 *   - 设置全局 API 信息（标题、版本、联系人等）
 *   - 配置 Swagger UI 行为（如启用 Try It Out）
 *
 * 注意：
 *   - 此类不定义任何具体服务的分组，仅提供“基础能力”
 *   - 所有配置会被业务模块继承并覆盖
 */
@Configuration
public class OpenApiConfig {

    /**
     * 注册所有公共 DTO 类型，让 OpenAPI 能正确识别其结构
     * 否则在 Swagger UI 中会显示为 "object" 或 "Unknown"
     *
     * 例如：UserBaseInfo、ResponseResult、PageRequest 等
     */
    @Bean
    public GroupedOpenApi commonModels() {
        return GroupedOpenApi.builder()
                .group("Common Models")
                .packagesToScan("io.urbane.commons.dto") // 扫描公共 DTO 包
                .build();
    }

    /**
     * 全局 API 信息（可被业务模块覆盖）
     * 所有服务默认使用此配置
     */
    @Bean
    public ApiInfo apiInfo() {
        return new ApiInfo(
                "Urbane Commerce API",
                "电商平台微服务统一接口文档\n" +
                        "所有服务遵循统一规范，支持 JWT 认证、幂等、链路追踪。",
                "v1.0",
                "https://urbane.io/terms-of-service",
                "api-support@urbane.io",
                "Apache 2.0",
                "https://opensource.org/licenses/Apache-2.0"
        );
    }

    /**
     * Swagger UI 全局配置
     * 控制前端展示行为
     */
    @Bean
    public SwaggerUiConfigParameters swaggerUiConfigParameters() {
        SwaggerUiConfigParameters config = new SwaggerUiConfigParameters();
        config.setTryItOutEnabled(true);             // 启用 "Try It Out" 功能
        config.setDisplayOperationId(true);          // 显示操作 ID，便于前端调用
        config.setDeepLinking(true);                 // 支持 URL 深度链接
        config.setShowExtensions(true);              // 显示扩展字段
        config.setFilter(true);                      // 启用搜索过滤
        config.setPersistAuthorization(true);        // 登录后持久化 Token
        return config;
    }
}